<!DOCTYPE html> 
<!--
 Copyright (c) 2010 - 2017 TU Wien ACIN, fortiss GmbH
               2019 Andrea Zoitl
  
 This program and the accompanying materials are made available under the
 terms of the Eclipse Public License 2.0 which is available at
 http://www.eclipse.org/legal/epl-2.0.

 SPDX-License-Identifier: EPL-2.0
 
 Contributors:
   Carolyn Oates, Monika Wenger, Milan Vathoopan, Jose Cabral 
     - initial API and implementation and/or initial documentation
   Andrea Zoitl
     - improved readability, updated Help ToC
-->

<html lang="en">
<head>
  <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
	<title>X+3 Tutorial</title>
	<link rel="stylesheet" type="text/css" href="../help.css">
</head>

<body>
<h1 id="topOfPage">Explore an Existing System</h1>
<p>This example gives you an overview of how to work with 4diac by examining and deploying the <span class="element61499">System</span> <span class="element4diac">Xplus3</span> and <span class="element61499">Application</span> <span class="element4diac">Xplus3Application</span>.
The <span class="element61499">System</span> consists of two <span class="element61499">Devices</span>, after examining the mapping of the <span class="element61499">Application</span> parts to the <span class="element61499">Resources</span>, we will set the preferences required and test it.</p> 

<ul>
	<li>Task of the X+3 example: calculate and display X+3.</li>
	<li>The <span class="element4diac">Xplus3 System</span> is included with the 4diac-IDE release, alternatively you can get it with mercurial <span class="inlineCode">hg clone http://hg.code.sf.net/p/fordiac/fordiac-systems</span> 
	<li>Examines a simple IEC 61499 <span class="element61499">Application</span> with 2 <span class="element61499">Devices</span>.</li> 
	<li>The communication between the different <span class="element61499">Devices</span> is integrated within the <span class="element61499">Resource</span>.</li>
</ul>

<h2 id="application">Explore Existing Application</h2>
<p>A IEC 61499 <span class="element61499">Application</span> is designed independent of <span class="element61499">Devices</span> and <span class="element61499">Resources</span>. The <span class="element61499">Application</span> FBs are mapped to the <span class="element61499">Resource</span> of a <span class="element61499">Device</span> they will run on after building the application. Click on the arrow beside the <span class="element4diac">Xplus3 System</span> and double-click to open the <span class="element4diac">Application</span> called <span class="element4diac">Xplus3Application</span> (note: depending on your operating system, a single click may be sufficient where double clicks are mentioned in this tutorial) 
<p>

<img src="../../html/examples/img/xplus3/x3_application.png" alt="X+3 TestApplication"/>

<p>There are 3 groups of Function Blocks connected. The specific color of a Function Block shows that this block is mapped to a <span class="element61499">Device</span>. The two different colors of the FBs indicate that they are mapped to two different <span class="element61499">Devices</span>, so the <span class="element61499">Application</span> is distributed. The dashed line connections are just information. We will see how the data is passed between <span class="element61499">Devices</span> in <span class="element61499">Resources</span>.</p>

<p>The <span class="element61499">Applications</span> IOs are on one <span class="element61499">Device</span> and the calculation (X+3) is on the 2nd <span class="element61499">Device</span>. Mouse over often provides extra information like a data variable's type. When exploring the <span class="element61499">Application</span> it can be figured out that there are three types of Function Blocks used</p>
<ul>
	<li><span class="element4diac">IN_ANY</span> and <span class="element4diac">OUT_ANY</span> are the input/output, which visualize the input value and the calculation result. The input <span class="element4diac">QI</span> is an input qualifier that allows the Function Block to work if its <span class="specificText">true</span>. It is used to turn-off Function Blocks when a predecessor Function Block has an error. In our <span class="element61499">Application</span> the <span class="element4diac">OUT_BOOL.QI</span> is set to <span class="specificText">1</span>.</li>
	<li><span class="element4diac">F_ADD</span> adds two <span class="element4diac">ANY</span> inputs together. One value comes from the input connection and the other is a hard-coded constant</li>
</ul>


<h2 id="systemManagement">Explore Existing <span class="element4diac">System Configuration</span></h2>
<p>Within the <span class="element61499">System</span> called <span class="specificText">Xplus3</span> there is the <span class="element4diac">System Configuration</span>. Click once on <span class="element4diac">System Configuration</span> (on left) and keep expanding the <span class="element4diac">System Configuration</span> by clicking the arrows on the left. This shows the <span class="element61499">Devices</span> and <span class="element61499">Resources</span> used.</p>

<img src="../../html/examples/img/xplus3/x3_systemConfiguration.png" alt="System Configuration"/>

<h3 id="devices">Explore Existing <span class="element61499">Devices</span></h3>
<p>Double click on <span class="element4diac">System Configuration</span> to open the <span class="element4diac">System Configuration</span> model that shows the <span class="element61499">System</span>, the <span class="element61499">Devices</span>, their <span class="element61499">Resources</span> and the communication network the <span class="element61499">Devices</span> are connected to.</p>

<img src="../../html/examples/img/xplus3/x3_system.png" alt="The X+3 System"/>

<p>There are two <span class="element4diac">Devices</span> connected via an Ethernet segment. You have to know what <span class="element4diac">Devices</span> you are using. Here it is:
<ol>
	<li><span class="specificText">MICROCONTROLLER</span> remote device (<span class="element4diac">RMT_DEV</span>) (uses FORTE). The IEC 61499 system used by this <span class="element61499">Application</span> <span class="element4diac">Xplus3Application</span> is Posix FORTE on a PC, but it could be a real microcontroller like ARM7 in Lego Mindstorms as well.</li>
	<li><span class="specificText">PC</span> remote frame (<span class="element4diac">RMT_FRAME</span>) (uses FBDK). The IEC 61499 <span class="element61499">System</span> used by this <span class="element61499">Application</span> <span class="element4diac">Xplus3Application</span> is FBDK via its runtime, FBRT.</li>
</ol> 

<p>Click on the <span class="element61499">Device</span> name in main window to look at the <span class="view4diac">Device's properties</span> bottom window. It is important to set the property Misc/Profile to HOLOBLOC.</p>

<h3 id="resources">Explore Existing <span class="element61499">Resources</span></h3>
<p>In this <span class="element61499">System</span> each <span class="element61499">Device</span> has a Manager and 1 <span class="element61499">Resource</span>, that <span class="element61499">Applications</span> can be mapped to. If you have not yet done so, click on the arrow at the left side of <span class="element4diac">System Configuration</span> to see the <span class="element61499">Devices</span> (<span class="element4diac">MICROCONTROLLER</span>; <span class="element4diac">PC</span>). In the same way, expand the <span class="element61499">Devices</span> (<span class="element4diac">MICROCONTROLLER</span>; <span class="element4diac">PC</span>) to see their <span class="element61499">Resource(s)</span>. Double-click on the <span class="element61499">Resource</span> names (<span class="element4diac">CALC</span>, <span class="element4diac">VIS</span>) to see what Function Blocks are mapped to the <span class="element61499">Resource</span>. For the <span class="element4diac">CALC Resource</span>, it looks like this: <span class="element4diac">System Configuration</span> &rarr; <span class="element4diac">MICROCONTROLLER</span> &rarr; <span class="element4diac">CALC</span></p>

<img src="../../html/examples/img/xplus3/x3_microcontroller.png" alt="Resource on the Microcontroller"/>

<p>And for the <span class="element4diac">VIS Resource</span>, like this: <span class="element4diac">System Configuration</span> &rarr; <span class="element4diac">PC</span> &rarr; <span class="element4diac">VIS</span></p>

<img src="../../html/examples/img/xplus3/x3_pc.png" alt="Resource on the PC"/>

<p>Note the <span class="element4diac">PUBLISH_1</span> and <span class="element4diac">SUBSCRIBE_1</span> Function Blocks that are used to send data between <span class="element61499">Devices</span> or <span class="element61499">Resources</span>. The <span class="specificText">_1</span> is the number of data items being sent / received. <span class="element4diac">INT2INT</span> is used multiple times. You may ask yourself: Why convert an <span class="element4diac">INT</span> to an <span class="element4diac">INT</span> - isn't that the same thing!? </p>

<ol>
	<li>Do a mouse over of the data output <span class="element4diac">IN_ANY.OUT</span> in <span class="element4diac">VIS</span>. Note its type: It is <span class="element4diac">ANY</span>.</li>
	<li>Do a mouse over of the data output <span class="element4diac">PUBLISH_1_0.SD_1</span>. Note its type: It is <span class="element4diac">ANY</span>.</li>
</ol>

<p>So, when the output type is <span class="element4diac">ANY</span> and the input type is <span class="element4diac">ANY</span>, how can the actual data type be known? This is why we need a conversion Function Block like <span class="element4diac">INT2INT</span> with <span class="element4diac">ANY</span> input and an actual data type for output. Funtion Blocks using an <span class="element4diac">ANY</span> type for input or output have to tell the Function Blocks the type in and the following Function Blocks the type out. For regular Function Blocks the input type must match its type. Look back at the <span class="element61499">Application</span>, where all 3 parts Input, Output and calculation appear together. Notice that the Publish and Subscribe Function Blocks used to exchange data between <span class="element61499">Resources</span> of a <span class="element61499">Device</span> are in the <span class="element61499">Resource</span> directly. This makes the <span class="element61499">Application</span> less cluttered and more clearly understandable.</p>



<h2 id="deployment">Deploy Your Application</h2>
<p>Switch to the <span class="view4diac">Deployment perspective</span> and set the runtime preferences. The following settings are under <span class="menu4diac">Window &rarr; Preferences &rarr; 4DIAC</span>. For further details on setting these locations see <a href="../../html/4diacIDE/overview.html#properties">4diac-IDE Properties</a>. To run the test, the locations of the IEC 61499 executables for the <span class="element61499">Devices</span> used are required.</p> 

<ul>
	<li><span class="element4diac">MICROCONTROLLER.CALC</span> uses FORTE. Therefore, the location of <span class="fileLocation">forte.exe</span> must be set within the FORTE preferences. Typically, this is somewhere below .<span class="folderLocation">/runtime/FORTE/</span>. Relative paths do not work in all setups, it is recommended to specify an absolute path here.</li>
	<li><span class="element4diac">PC.VIS</span> uses FBRT. Therefore, the location of <span class="fileLocation">fbrt.jar</span> must be set in FBRT preferences. Typically, this path is <span class="fileLocation">./runtime/FBRT/fbrt.jar</span>.</li>
</ul>

<p>With the preferences set correctly for the IEC 61499 <span class="element61499">System</span> on the 2 <span class="element61499">Devices</span> you can now test. Click the Open perspective button on top of the title bar and add Deployment in the perspective window. The Open Perspective button of the Deployment perspective will be found besides the <span class="button4diac">System</span> perspective Button</p>

<img src="../../html/examples/img/xplus3/x3_deployment.png" alt="Deployment of the X+3 Application"/>

<p>To download and test your IEC 61499 <span class="element61499">Application</span>:</p>

<ol>
	<li>Check the <span class="element4diac">System Xplus3</span> and notice the <span class="element61499">Devices</span> show up under the <span class="element61499">System</span>, but not the <span class="element61499">Application</span> mapped to the <span class="element61499">Devices</span>.</li>
	<li>Press the Launch FBRT button. Note that the <span class="element61499">Device</span> and port number match the properties of the <span class="element61499">Device</span> using FBRT (i.e., <span class="element4diac">PC</span>) in <span class="element4diac">System Configuration</span>. The console output from the FBRT is shown on the bottom right and an empty Java window will open.</li>
	<li>Press the Launch FORTE button. Note that the host and port number match the properties of the <span class="element61499">Device</span> using FORTE (i.e., <span class="element4diac">MICROCONTROLLER</span>) in <span class="element4diac">System Configuration</span>. Again, console output is shown on the bottom right. The console output of FORTE is dependent on the log-level that has been configured with CMake. The default configuration is LOGDEBUG. It lists debug information.</li>
	<li>When launching FBRT or FORTE for the first time, a system firewall configuration window may pop up. You should allow network access that the 2 <span class="element61499">Devices</span> are able to communicate with each other over Ethernet.</li>
	<li>Press Download and notice the Deployment Console output on the right. Click on the Java application window (<span class="element4diac">RMT-FRAME</span>). Resize it if necessary to see the contents. Enter an integer in the top field and press the enter key. The result is shown in the bottom field: It should be the value you entered plus three.</li>
</ol>

<h1>Where to go from here?</h1>

<p>Go back to Examples index:</p>

<p><a href="../../html/examples/examplesIndex.html">Examples Index</a></p>

<p>If you want to go back to the Start Here page, we leave you here a fast access</p>

<p><a href="../../html/startHere/startHere.html">Start Here page</a></p>

<p class="goToTop"><a href="#topOfPage">Go to top</a></p>

</body>
</html>